// This file provides a function to generate structured help documentation
// for all CLI commands, formatted as Markdown content.

import { Command, program } from "commander"

/**
 * Generates and prints a structured help document for all CLI commands.
 * The output is formatted as Markdown content with a focus on creating documentation.
 *
 * The function includes a recursive helper to process commands and their subcommands,
 * generating Markdown headers and help text for each command.
 *
 * @param header - The Markdown header level as a string, used to format the documentation.
 * @param parent - The parent command, which may be undefined for top-level commands.
 * @param commands - An array of Command objects to process, including subcommands.
 */
export async function helpAll() {
    // Print the front matter for the documentation
    console.log(`---`)
    console.log(`title: Commands`)
    console.log(`description: List of all CLI commands`)
    console.log(`sidebar:`)
    console.log(`  order: 100`)
    console.log(`---\n`)

    // Indicate that the following content is autogenerated
    console.log(`<!-- autogenerated, do not edit -->`)
    console.log(`A full list of the CLI command and its respective help text.`)

    /**
     * Recursive function to visit all commands and their subcommands.
     * Processes each command and generates corresponding Markdown documentation.
     *
     * @param header - The Markdown header level as a string.
     * @param parent - The parent command, which may be undefined for top-level commands.
     * @param commands - An array of Command objects to process.
     */
    const visit = (
        header: string,
        parent: Command,
        commands: readonly Command[]
    ) => {
        commands.forEach((c) => {
            // Construct and print the command's header in Markdown
            console.log(
                `\n${header} \`${[parent?.name(), c.name()].filter((c) => c).join(" ")}\`\n`
            )
            // Print the command's help output in a code block
            console.log("```")
            c.outputHelp()
            console.log("```")

            // If the command has subcommands, recursively visit them
            if (c.commands?.length) {
                visit(header + "#", c, c.commands)
            }
        })
    }

    // Start the recursive visit function with top-level commands
    visit("##", undefined, program.commands)
}
